.\" iPCRess man Page
.TH ipcress 1 "March 2003" ipcress "PCR simulation tool"
.SH NAME
.\"
ipcress \- In-silico PCR experiment simulation system
.SH SYNOPSIS
.B ipcress [ options ] <primer file> <sequence paths>

.SH DESCRIPTION
.BR ipcress
is the
.IR I n-silico
.IR PCR
.IR E xperiment
.IR S imulation
.IR S ystem.

This is a tool for simulation of PCR experiments.
You supply a file containing primers and a set of sequences,
and it predicts PCR products.
.P
.\"
Ipcress is similar to the e-PCR program from the NCBI,
but is much faster, and does not suffer from problems
identifying matches when there are ambiguity symbols
near primer ends.
.P
.\"
If you supply many primers pairs together,
ipcress will simulate the PCR experiments in parallel,
allowing genome wide simulation of large numbers of experiments.
It uses many libraries from the
.B exonerate
sequence comparison tool.
.\"
.RE
.SH INPUT FORMAT
.T
The input for ipcress is a simple white-space delimited file
describing one experiment per line.  Each line contains
the following 5 fields:
.\"
.PP
.RS
.PD 0
.\"
.TP 18
.B id
An identifier for this experiment
.\"
.TP 18
.B primer_A
Sequence for the first primer
.\"
.TP 18
.B primer_B
Sequence for the second primer
.\"
.TP 18
.B min_product_len
Minimum product length to report
.\"
.TP 18
.B max_product_len
Maximum product length to report
.\"
.PD
.RE
.P
Here is an example line in this format:
.SP
.nf

ID0001 CATGCATGCATGC CGATGCANGCATGCT 900 1100
.SP
.fi
.\"
.RE
.SH OUTPUT FORMAT
.T
The output format describes one PCR product per-line,
and is prefixed by "ipcress:", followed by the following 11 fields:
.\"
.PP
.RS
.PD 0
.\"
.TP 16
.B sequence_id
The sequence identifier
.\"
.TP 16
.B experiment_id
The PCR experiment id
.\"
.TP 16
.B product_length
The PCR product length
.\"
.TP 16
.B primer_5
The 5' primer (either A or B)
.\"
.TP 16
.B pos_5
Position of the 5' primer
.\"
.TP 16
.B mismatch_5
Number of mismatches on 5' primer
.\"
.TP 16
.B primer_3
|
.\"
.TP 16
.B pos_3
| Same fields for the 3' primer
.\"
.TP 16
.B mismatch_3
|
.\"
.TP 16
.B description
A description of the PCR product
.\"
.PD
.RE
.P
.\"
The description field is one of the following 4 strings:
.\"
.PP
.RS
.PD 0
.\"
.TP 10
.B forward
Normal product, primer A followed by B
.\"
.TP 10
.B revcomp
Normal product, primer B followed by A
.\"
.TP 10
.B single_A
Bad product generated by primer_A only
.\"
.TP 10
.B single_B
Bad product generated by primer_B only
.\"
.PD
.RE
.P
.\"
There is also a human-readable output displayed,
is not designed for parsing (see: --pretty below).
.\"
.RE
.SH GENERAL OPTIONS
.T
Most arguments have short and long forms.  The long forms
are more likely to be stable over time, and hence should
be used in scripts which call ipcress.
.\"
.TP
.B "\-h | \--shorthelp" <boolean>
Show help.
This will display a concise summary of the available options,
defaults and values currently set.
.\"
.TP
.B "--help" <boolean>
This shows all the help options including the defaults,
the value currently set,
and the environment variable which may be used to set each parameter.
There will be an indication of which options are mandatory.
Mandatory options have no default, and must have a value supplied
for ipcress to run.  If mandatory options are used in order,
their flags may be skipped from the command line (see examples below).
Unlike this man page, the information from this option will always
be up to date with the latest version of the program.
.\"
.TP
.B "\-v | \--version" <boolean>
Display the version number.  Also displays other information
such as the build date and glib version used.
.RE
.\"
.SH FILE INPUT OPTIONS
.TP
.B "-i | \--input " <path>
PCR experiment data in the ipcress file format described above.
.TP
.B "-s | \--sequence" <paths>
Specify the sequences.
Multiple files may be specified here,
which reduces the FSM building overhead, and makes ipcress
run faster than running the process separately.
.RE
.\"
.SH IPCRESS PARAMETERS
.TP
.B "\-m | \--mismatch " <mismatches>
Specify the number of mismatches allowed per primer.
Allowing mismatches reduces the speed of the program
as a large primer neighbourhood must be constructed,
and fewer experiments can be fitted in memory prior
to each scan of the sequence databases.
.\"
.TP
.B "\-M | \--memory" <Mb>
Specify the amount of memory the program should use.
The more memory made available ipcress, the faster
it will run, as more PCR experiments can be conducted
in each scan of the sequence databases.
This does not include memory used during the scan
(for storing partial results and sequences), so the
actual amount of memory used will be slightly higher.
.\"
.TP
.B "\-p | \--pretty" <boolean>
Display results in a human-readable format, not designed for parsing.
.\"
.TP
.B "\-P | \--products" <boolean>
Display PCR products as a FASTA format sequence.
.\"
.TP
.B "\-S | \--seed" <length>
Specifiy the seed length for the wordneighbourhood for the FSM.
If set to zero, the full primer is used.
Shorter words reduce the size of the neighbourhood,
but increase the time taken by ipcress to filter
false positive matches.
.\"
.SH ENVIRONMENT
Not documented yet.
.\"
.SH EXAMPLES
.\"
.B "ipcress test.ipcress sequence.fasta"
.RS
This is the simplest way that ipcress can be used.
.RE
.\"
.B "ipcress dbsts_human.ipcress --sequence ncbi30/*.fasta --mismatch 1"
.RS
Compare a input file against a set of fasta files,
allowing one mismatch in each primer.
.RE
.\"
.RE
.SH VERSION
This documentation accompanies version 2.2.0 of the exonerate package.
.\"
.SH AUTHOR
Guy St.C. Slater.  <guy@ebi.ac.uk>.
.L
See the AUTHORS file accompanying the source code
for a list of contributors.
.SH AVAILABILITY
This source code for the exonerate package is available
under the terms of the GNU
.I general
public licence.

Please see the file COPYING which was distrubuted with this package,
or http://www.gnu.org/licenses/gpl.txt for details.

This package has been developed as part of the ensembl project.
Please see http://www.ensembl.org/ for more information.
.SH "SEE ALSO"
.BR exonerate (1), e-PCR
